QuickTime 4 Reference

Low-level Functions

These functions provide more complex and comprehensive interfaces to the effects dialog functionality. Using the low-level functions, you can gain more control over the standard parameters dialog box, such as the ability to incorporate user interface elements from the dialog box into your own application-defined dialog box.

ImageCodecGetParameterList

The ImageCodecGetParameterList function returns a parameter description data structure for the specified component instance.



 
ComponentResult ImageCodecGetParameterList (

                     ComponentInstance ci,

                     QTAtomContainer *parameterDescription);

ci: An instance of an effect component.
parameterDescription: The returned parameters description data structure for this component instance.

DISCUSSION

This function returns the parameter description for the effect specified by the component instance ci . The parameter description is a set of QTAtom data structures stored inside a QTAtomContainer . Each parameter of the effect is described in the parameter description, with details of its name, type, legal values and hints about how a user interface to the parameter should be constructed.

For full details of the set of atoms stored in a parameter description, see "The Parameter Description Format" .

SPECIAL CONSIDERATIONS

The calling application is responsible for disposing of the QTAtomContainer returned in parameterDescription . The application should do this by calling QTDisposeAtomContainer once it has finished using the parameter description.

ImageCodeCreateStandardParameterDialog

This function creates a parameters dialog box for the specified effect. The dialog box allows the user to set the parameter values for the effect. You can optionally request that the controls from the dialog box be included within a dialog box of the calling application.



 
ComponentResult ImageCodecCreateStandardParameterDialog (

                     ComponentInstance ci,

                     QTAtomContainer parameterDescription,

                     QTAtomContainer parameters,

                     QTParameterDialogOptions dialogOptions,

                     DialogPtr existingDialog,

                     short existingUserItem,

                     QTParameterDialog *createdDialog);

ci: An instance of an effect component. The dialog box that is created will allow the user to specify the parameters of this effect.
parameterDescription: The parameter description for this effect. You can obtain a valid parameterDescription by calling ImageCodecGetParameterList .
parameters: The container that will receive the user's chosen parameter values once the dialog has been dismissed.
dialogOptions: Control over how parameters containing tween data are presented in the created dialog box. If dialogOptions contains 0 , two values are collected for each parameter that can be tweened, and the usual tweening operation will be performed for the duration of the effect being controlled.; If dialogOptions contains pdOptionsCollectOneValue , only one value can be entered for parameters that are optionally tweenable. This means that optionally-tweened parameters will not be tweened.; If dialogOptions contains pdOptionsAllowOptionalInterpolations , the user interface for optionally-tweened parameters will be constructed to take tweened values. Setting this flag selects the "advanced" user interface mode described in "Parameter Atom Type and ID" .; Parameters are optionally tweenable if defined as kAtomInterpolateIsOptional in their parameter description.
existingDialog: An existing dialog box that will have the controls from the standard parameters dialog box added to it. Set this parameter to nil if you want ImageCodecCreateStandardParameterDialog to create a stand-alone dialog box. .
existingUserItem: The number of the user item in the existing dialog box that should be replaced with controls from the standard parameter dialog box. You should only pass a value to this parameter if the existingDialog parameter is not nil .
createdDialog: On exit, this parameter contains a reference to the dialog created and displayed by the function. This reference is required by several other low-level effects functions. It will contain a valid dialog identifier even if you requested that the controls from the standard parameter dialog box be incorporated into an existing dialog box.

DISCUSSION

This function can be used to create a standard parameter dialog box for a specified effect, or it can add the controls from the standard parameter dialog box to an existing dialog box provided by the calling application.

The high-level version of this function is QTCreateStandardParameterDialog .

ImageCodecIsStandardParameterDialogEvent

This function processes events related to a standard parameters dialog box creeated by ImageCodecCreateStandardParameterDialog .



 
ComponentResult ImageCodecIsStandardParameterDialogEvent (

                     ComponentInstance ci,

                     EventRecord *pEvent,

                     QTParameterDialog createdDialog);

ci: An instance of an effect component. This must be the instance that was passed to ImageCodecCreateStandardParameterDialog to create the dialog box.
pEvent: A pointer to an event record returned by WaitNextEvent .
createdDialog: A reference to the dialog box created by the call to ImageCodecCreateStandardParameterDialog .

ImageCodecIsStandardParameterDialogEvent returns an error code that indicates whether the event pointed to by pEvent was processed or not. If the error code returned is featureUnsupported , your application should process the event in the normal way. If the ImageCodecIsStandardParameterDialogEvent returns any other value, the event was processed or an error occurred.

RESULT CODES

`featureUnsupported`	The event was not processed by the function. Your application should process the event normally.
`codecParameterDialogConfirm`	The user clicked the OK button in the dialog box. Your application should call `ImageCodecStandardParameterDialogDoAction` , then `ImageCodecDismissStandardParameterDialog.`
`userCanceledErr`	The user clicked the Cancel button in the dialog box. Your application should call `ImageCodecDismissStandardParameterDialog.`

DISCUSSION

After you call ImageCodecCreateStandardParameterDialog to create a standard parameter dialog box, you must pass every non-null event return from WaitNextEvent to ImageCodecIsStandardParameterDialogEvent . The function processes events related to the standard parameter dialog box, passing other events to your application for processing.

The high-level version of this function is QTIsStandardParameterDialogEvent . Use the high-level version to handle events for dialog boxes created by QTCreateStandardParameterDialog .

ImageCodecStandardParameterDialogDoAction

This function allows you to control the behaviour of a standard parameter dialog box created by ImageCodecCreateStandardParameterDialog . You specify which function will be performed by passing an action selector in the action parameter and, optionally, a single parameter in params .

Some of the actions you can specify through this function are only appropriate if you have incorporated standard parameter dialog box controls within a dialog box created by your application.



 
ComponentResult ImageCodecStandardParameterDialogDoAction (

                     ComponentInstance ci,

                     QTParameterDialog createdDialog,

                     long action,

                     void *params);

ci: An instance of an effect component. This must be the same instance as was passed to ImageCodecCreateStandardParameterDialog to create the dialog box.
createdDialog: A reference to the dialog box created by the call to ImageCodecCreateStandardParameterDialog .
action: The action selector, which determines which of the available actions you want the function to perform. The following list describes the available action selectors:; pdActionConfirmDialog Retrieves the current parameter values from the standard parameters dialog box. The parameter values are placed in the parameters parameter that was passed to the appropriate call to ImageCodecCreateStandardParameterDialog .; Use this action when the user clicks the OK button in a dialog box your application has created that incorporates controls from the standard parameter dialog.; If you created a stand-alone standard parameters dialog box, this action is automatically called for you when the user clicks the OK button.; pdActionSetAppleMenu Use this selector to make the Apple menu available while the standard parameter dialog box is active. Pass the MenuHandle of the Apple menu in the params parameter.; pdActionSetEditMenu Use this action to make your application's Edit menu available while the standard parameters dialog box is active.Pass the MenuHandle of the Edit menu in the params parameter.; pdActionGetDialogValues Retrieves the current parameter values from the standard parameters dialog box. The parameter values are placed in the QTAtomContainer you pass in the params parameter to this call.; pdActionSetPreviewUserItem Passes the number of the user item that should be replaced by the effect preview movie clip. The params parameter contains a long integer holding the user item number.; pdActionSetPreviewPicture Use this action to change the images that are used in the preview window of the standard parameters dialog box. QuickTime provides default images but you may wish, for example, to use thumbnail images taken from your application instead. The params parameter contains a QTParamPreviewPtr referencing the image to use (see "Parameter Dialog Box Preview Image Specifier" ).; pdActionSetColorPickerEventProc Set the function that will be used when the standard parameters dialog box needs to display a color picker. The params parameter should contain a UserEventUPP that points to the replacement color picker function.; pdActionSetDialogTitle Sets the title of the standard parameters dialog box. The params parameters should contain a Pascal Str255 string.; pdActionGetSubPanelMenu Returns a list of the sub-panels used by the standard parameters dialog box. If there are more parameter controls than can fit into the available area of the dialog box, the parameters are automatically split into sub-panels (usually by segmenting the set of parameters by group). The pop-up menu used to switch between the panels is returned as a MenuHandle in the params parameter.; pdActionActivateSubPanel Sets the current sub-panel. The params parameter contains a long integer that is the number of the panel to be displayed.; pdActionConductStopAlert Displays a Stop alert. The params parameter contains a StringPtr that is displayed in the alert. This feature can be used in conjunction with the ImageCodecValidateParameters function to inform the user that invalid parameter values have been entered.
params: The (optional) parameter to the action. The type passed in this parameter depends on the value of the action parameter.

DISCUSSION

The ImageCodecStandardParameterDialogDoAction function allows you to change the default behavior of the standard parameter dialog box, and provides a mechanism for your application to communicate with controls that were incorporated into an application dialog box. It also allows you to retrieve parameter values from the dialog box at any time.

This function is only used with dialog boxes created by the low-level ImageCodecCreateStandardParameterDialog function. For dialog boxes created by the high-level QTCreateStandardParameterDialog function, use QTStandardParameterDialogDoAction .

ImageCodecDismissStandardParameterDialog

This function retrieves values from a standard parameter dialog box created by the low-level ImageCodecCreateStandardParameterDialog function, then closes the dialog box.



 
ComponentResult ImageCodecDismissStandardParameterDialog (

                     ComponentInstance ci,

                     QTParameterDialog createdDialog);

ci: An instance of an effect component. This must be the same instance as was passed to ImageCodecCreateStandardParameterDialog to create the dialog box.
createdDialog: A reference to the dialog box created by the call to ImageCodecCreateStandardParameterDialog .

DISCUSSION

This function should be called after the ImageCodecIsStandardParameterDialogEvent function returns codecParameterDialogConfirm or userCanceledErr , which indicate that the user has dismissed the dialog box.

The function dismisses the dialog box, deallocating any memory allocated during the call to the ImageCodecCreateStandardParameterDialog function.